fix(types): refuse a bare exportOptions array on the object-grid zod mirror - #8485

Fixes #7762

Lane domain:spec. Clause-②: yes — this narrows a published accept set, so needs:contract-review is hung on this PR and it stays draft: not enqueued, no auto-merge, no self-approval. Parking green at the gate is the sanctioned resting state.

packages/plugin-grid/** is untouched. The routing ruling holds the renderer's read to be correct, and nothing in this change needed it to move.

What was wrong, measured on origin/main c90395b

ObjectGridSchema in packages/types/src/zod/objectql.zod.ts declared no exportOptions member, and BaseSchema is .passthrough(). Taken on a built tree:

'exportOptions' in ObjectGridSchema.shape        -> false
  live control    'bulkActions'                  -> true
  negative control 'zzNoSuchKey'                 -> false

safeParse({type:'object-grid', objectName:'accounts', exportOptions:['csv','xlsx']})
  -> success TRUE, data.exportOptions = ["csv","xlsx"]              VERBATIM
safeParse({... exportOptions:{formats:['csv','pdf'],compression:'gzip'}})
  -> success TRUE, returned VERBATIM

ObjectGrid.tsx reads schema.exportOptions?.formats and only that, and the effect that warns about dropped formats reads .formats too and returns early when it is absent, so the authored array then lost silently to the ['csv','json'] default with the export button still on screen. The card's premise re-measured green in full, against @objectstack/spec@17.3.0.

What this does

Declares the member as the spec's object arm, peeled out of SpecListViewSchema.shape.exportOptions and bound by reference, re-wrapped so its invalid_type message names the shape the renderer reads.

bare array ['csv','xlsx']                  -> ONE issue, code invalid_type, path ['exportOptions'],
                                              message naming { formats: [...] }
five-key object                            -> success TRUE, returned VERBATIM (streaming survives)
{ formats:['csv','pdf'] }                  -> refused, spec's own migration prescription
                                              ("'csv', 'xlsx' and 'json'", "os migrate meta")
{ formats:['csv'], compression:'gzip' }    -> refused, unrecognized_keys naming compression
node with no exportOptions                 -> unchanged, success TRUE

⛔ Not SpecListViewSchema.shape.exportOptions itself. That reference is a two-arm union whose first arm LIFTS a bare array to { formats } at parse; binding it would make this mirror accept-and-lift, the opposite of the ruled refusal. The sibling list-view mirror keeps that binding and keeps lifting — pinned as a live control in the new test.

Peeled rather than restated: a local copy of the five keys is a third copy of one contract, and the copy is what drifts. Every member schema is the spec's own object, asserted by toBe identity.

One correction worth recording, because it is invisible in the diff: the shape must be typed by the same two steps at the type level (unwrap, then the arm carrying a shape). Annotating it z.ZodRawShape compiles and builds, but collapses every member of the authoring face to unknown — measured, the drift ledger reported exportOptions NARROWER than declared. Recorded in the source comment so it is not reintroduced.

The re-derived ledger edit set, with its firing control

Every figure below was re-derived on current origin/main, symbol-located. Nothing was carried in from the card or any comment, and the previous round's addresses are all stale — PR #8354 rewrote that file after them.

Two figures the predecessor's enumeration did not have and one that changed shape: the pair also moves between the split's halves. Binding a Spec… symbol inside this mirror's initializer makes specReferencingExports re-derive the pair, so SPEC_DERIVED_PAIRS must gain it — the #7779 membership mechanism a second time. Measured, not reasoned: with the member added and the list untouched, SPEC_DERIVED_PAIRS matches what the mirror sources actually do failed with expected [ …(12) ] to deeply equal [ …(11) ]. The entry docblock records that the half is MEMBERSHIP and that the fourteen remaining keys are still ordinary local omissions, the reading #7279 kept on ObjectViewSchema for the same reason.

The two historical figures pinned at named revisions (beccf1c6b / ed7178bf3) are deliberately not touched — they cannot rot and must not chase the ledger.

The firing control. pnpm --filter @object-ui/types type-check is the instrument; vitest run …zod-mirror-parity.test.ts cannot see the type-level reconciliation at all, because the ledger is a TYPE map and vitest does not typecheck. Run TWICE, and both runs are reported because they measure different directions.

Leg A — on the pre-fix tree c90395b, the direction "a member appears". The mutation was the most generic member possible, exportOptions: z.any().optional():

CONTROL   clean tree, blob 4ddc342c… == that tree's blob   type-check -> exit 0, no diagnostics
ABLATION  one z.any() member injected, blob 5e201199…      type-check -> exit 2
          tsc's own line:
          src/__tests__/zod-mirror-parity.test.ts(2414,14): error TS2322:
            Type "objectql.zod.ts#ObjectGridSchema" is not assignable to type 'never'.
FALSE     the SAME mutated tree, vitest on that file       -> exit 0, "Tests 31 passed (31)"
GREEN
RESTORE   git checkout HEAD -- (the path); blob equality and an empty `git diff HEAD`,
          ⛔ not an exit code

⚠️ That :2414 is an address in the PRE-EDIT file, and it is not quoted as if it described this head: this PR's own ledger edits add lines above the assertion and move it. Leg B is the reading about the tree a reviewer checks out.

Leg B — re-run on head 1ee7f72d, the direction that applies now. The key is mirrored here, so the firing mutation is DELETING the member while the ledger row stays shrunk:

CONTROL   clean head 1ee7f72d, blob 37f6f962… == HEAD blob  type-check -> exit 0, no diagnostics
ABLATION  the member deleted, blob e41bea4e…                type-check -> exit 2
          tsc's own line:
          src/__tests__/zod-mirror-parity.test.ts(2444,14): error TS2322:
            Type "objectql.zod.ts#ObjectGridSchema" is not assignable to type 'never'.
RESTORE   blob back to 37f6f962…, `git diff HEAD` empty, ⛔ not an exit code

⚠️ On this head the same mutation ALSO reddens vitest — but through a DIFFERENT assertion, the runtime census SPEC_DERIVED_PAIRS matches what the mirror sources actually do (1 failed | 30 passed). The type-level reconciliation stays invisible to vitest: it is not one of that file's 31 runtime tests. The false-green warning is unchanged by vitest happening to fail here for another reason.

⚠️ One probe on this head returned a NULL reading and is reported rather than dropped: a member named zzLedgerProbe left type-check at exit 0. That is the probe testing the wrong direction — an UNDECLARED mirror key is not an UnmirroredDeclared ledger key — not evidence the instrument is asleep. Leg B is the valid control.

The new pin, and its ablation

packages/types/src/__tests__/object-grid-export-options-refusal-7762.test.ts — 11 tests: a non-vacuity floor that the spec arm is found with its five keys, shape membership with a live and a negative control, toBe identity per member, the "not the spec union" control (which also asserts list-view still lifts), the four authored readings, and three non-regression controls.

Ablated on the committed tree by deleting the member and running the pin: 6 of 11 red, and the 5 that stayed green are exactly the ones that must — the floor, the "not the union" control, the five-key object still accepted, the empty node, and the neighbouring members. Restored by git checkout HEAD -- the path, proved by blob equality (37f6f962…, this head) and an empty git diff HEAD.

Gates, derived from the changed-file set

Exit codes captured by redirect before any pipe.

The downstream leg is the whole consumer closure, not a narrowing: @object-ui/types is the protocol package and this change moves its published z.input face, so every consumer was rebuilt (each package's build is tsc). Provenance: every figure in the table above was re-measured on head 1ee7f72d — the build, the type-check, the 145/2766 suite, the pin, the pin ablation, lint, all eleven check:* gates, the governed-surface probe, the 7-file consumer set and the 42-package closure. ⛔ Nothing here is a 29c0479 number relabelled with a newer sha. The two readings that are NOT from this head are labelled where they appear, and are readings about a different tree by design: the pre-fix baseline (taken on origin/main — that is the point of it) and firing-control Leg A (taken on c90395b, with Leg B re-run on this head). Heavy runs went through scripts/pm/os-verify-lock.sh with OS_VERIFY_LOCK_SLOT=issue-7762-objectui; verdicts read from its own VERDICT command-exit lines.

Console framework budget — merged main, and the bytes recovered

origin/main (61e649a) is merged in as 3ab8e40 (--no-ff, no conflicts, ⛔ no rebase / amend / force-push). The framework chunk is packages/(core|react|types), so this PR's published strings land in it.

Two legs, both built and measured locally:

⇒ The ceiling is not saturated: main is healthy and the 391-byte delta is this PR's. Two reductions were taken, each measured before choosing, and each pure redundancy removal that loses no fact:

• the module-load throw message, 272 → 144 raw bytes — worth 35 gzip bytes. It still names the moved spec symbol, the member that depends on it and the card; the rationale it used to restate lives in the docblock above it, which the production minifier strips while the string ships.
• two phrases in the shared guidance string, 378 → 363 raw bytes — worth 8 gzip bytes. "grid toolbar export menu" → "grid toolbar menu" after a sentence that already opens "Export configuration", and "would be dropped in silence" → "is silently dropped".
• rejected: the peel's typeof cur.unwrap === 'function' predicate (an estimated 5–8 gzip bytes, deliberately not measured). A non-function truthy unwrap would then raise a TypeError instead of the diagnostic Error, which weakens the module-load guard.

⛔ PER_CHUNK_GZIP_CEILINGS.framework and PER_CHUNK_BASELINE are untouched — git diff origin/main -- scripts/check-eager-closure-budget.mjs is empty. Nothing was skipped, disabled or quarantined.

⚠️ The margin is ONE gzip byte, and that is a fact about the ceiling rather than about this PR. main itself only had 349 bytes of headroom on a chunk whose ceiling was last raised for an unrelated spec bump. The next card that adds any published string or schema member to packages/(core|react|types) hits this wall with nothing left to trim. Raising it is a maintainer-floor action and was not taken here; flagging it so the decision gets taken deliberately instead of discovered by the next lane.

The accept set did not move with the bytes. Verdict sets compared across the two blobs, same probe, rebuilt dist each time:

                pre-patch 7e1929d7…              post-patch 37f6f962…
bare array      invalid_type@exportOptions       invalid_type@exportOptions
['csv','pdf']   invalid_type@exportOptions       invalid_type@exportOptions
{formats:pdf}   invalid_value@exportOptions.formats.1   (identical)
five-key        ACCEPT                           ACCEPT
sixth key       unrecognized_keys@exportOptions  (identical)
no key          ACCEPT                           ACCEPT

Only the message LENGTH moved (376 → 361 characters). And the pin's own assertions re-verified on 1ee7f72d: /formats/ ✅, /list-view/ ✅, /object-grid/ ✅, and description === refusal message ✅ (both 363 UTF-8 bytes). list-view still LIFTS a bare array to { formats: ['csv','xlsx'] } and still refuses 'pdf' — no sideways leak. ObjectViewSchema.table.exportOptions moves with the change (it is ObjectGridSchema.omit(…).partial()): base accepted a bare array there, this head refuses it, the object form parses on both, and it has zero runtime readers — named in the changeset rather than left to be discovered.

⚠️ On object-grid the retired 'pdf' value is reachable only through the OBJECT spelling. The ARRAY spelling ['csv','pdf'] is refused earlier, by the named refusal, before the format enum is consulted — correct and intended, since the array form is not admitted on this node at all.

Fixture triage

Repo-wide sweep for an authored array spelling (git grep -n "exportOptions['\"]\?: *\["): four hits, none on an object-grid node — one changeset prose line, and three list-view fixtures (ListView.test.tsx, export-options-spec-parity.test.ts, p1-spec-alignment.test.ts) whose spelling is still legal there and is asserted to keep lifting. No fixture is owed a change.

验收备注

• packages/plugin-grid/src/index.tsx's designer description for exportOptions still lists four keys and omits streaming. Noted, not filed: it is already recorded in the card body and routed by triage into its shard A table, and plugin-grid is read-only for this lane.
• Triage's shard A (a ListView-style fold at ObjectGrid's read site) is REFUSED by the routing ruling, which holds the renderer's read correct. Recorded so a later reader does not resurrect it.
• The ruling's cost argument, quoted verbatim and re-measured TRUE: 「收窄不弄坏任何今天能用的东西」 — the refused spelling was already a silent no-op, so the narrowing costs no working artefact.

🤖 Generated with Claude Code

https://claude.ai/code/session_01CZY49skxUBYyJcdnTcYPrE

Authored by Claude Code in session session_01CZY49skxUBYyJcdnTcYPrE (durable attribution in prose, so an edit does not accrete footer blocks).

Generated by Claude Code